docs: Add CLI documentation and version flag support#46
Merged
Conversation
Adds CLI documentation infrastructure from tmuxp#1010: - sphinx_argparse_neo extension for argparse rendering - argparse_lexer for syntax highlighting - argparse_roles for semantic CLI markup - argparse_exemplar for clean output formatting
Tests for CLI documentation extension from tmuxp#1010
Biome-formatted CSS with consolidated light mode headerlink selectors
- Add argparse_exemplar to Sphinx extensions - Add argparse-highlight.css to html_css_files - Add mypy overrides for sphinx_argparse_neo modules - Exclude tests/docs from mypy strict checking
Replace tmuxp-specific examples with inline test module creation that works in any repository without external dependencies
Add type stubs (types-docutils, types-Pygments) and configure mypy with mypy_path and explicit_package_bases for proper module resolution. - Add missing files: __init__.py, cli_usage_lexer.py, conftest.py - Fix type narrowing in directive.py (use subparser variable) - Remove redundant cast and unused type: ignore comments
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## master #46 +/- ##
==========================================
+ Coverage 76.24% 83.71% +7.47%
==========================================
Files 5 25 +20
Lines 181 2235 +2054
==========================================
+ Hits 138 1871 +1733
- Misses 43 364 +321 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Member
Author
Code reviewFound 2 issues:
g/docs/_ext/argparse_exemplar.py Lines 208 to 214 in dc4dd7c
Lines 138 to 141 in dc4dd7c 🤖 Generated with Claude Code - If this code review was useful, please react with 👍. Otherwise, react with 👎. |
Replace commented pseudo-code with working doctest using types.SimpleNamespace to demonstrate config value extraction and default fallback behavior.
Change `conftest\.py$` to `docs/_ext/conftest\.py$` to type-check root conftest.py while avoiding duplicate module error from mypy_path config.
- Add create_parser() function to g module for documentation and --version - Create docs/cli/index.md using sphinx-argparse directive - Add cli/index to docs toctree - Support --version/-V flag in CLI
- feat(docs): Render argparse metadata as semantic definition list Replace pipe-separated format with <dl>/<dt>/<dd> structure - style(css): Use var(--code-font-size) for all argparse elements Add font-size to inline roles, pre.argparse-usage, .argparse-argument-name Add new .argparse-argument-meta flexbox styles - fix(lexer): Include underscores in lowercase metavar patterns Change [a-z][-a-z0-9]* to [a-z][-a-z0-9_]* in 6 locations - test(lexer): Add underscore metavar regression test Add fixtures and test for socket_name, config_file patterns
Member
Author
Code reviewNo issues found. Checked for bugs and CLAUDE.md compliance. 🤖 Generated with Claude Code - If this code review was useful, please react with 👍. Otherwise, react with 👎. |
The previous implementation used argparse's version action which calls sys.exit(), preventing run() from returning in test mode. Now version is printed manually and returns None when G_IS_TEST is set, matching the pattern used when no VCS is found. Adds tests for --version and -V flags.
The documentation previously stated "all arguments are passed directly" which was misleading since --version/-V is intercepted by g itself. Updated epilog and documentation to accurately describe this behavior.
Furo's "auto" theme follows system prefers-color-scheme. The meta tag dark styling only targeted explicit data-theme="dark", missing the auto-dark case where body:not([data-theme="light"]) applies.
The light mode override for headerlink colors used body:not([data-theme="dark"]) which incorrectly matches auto mode even when system is dark. Split into explicit light selector plus media query for auto + system light.
- CLI: g --version/-V now displays g's version - Documentation: Add CLI documentation page - Documentation: Linkable anchors for CLI arguments
Replace tmuxp-specific examples with generic "myapp" in doctests and comments.
Replace tmuxp examples in tests with generic "myapp".
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds CLI documentation infrastructure and improves CLI usability:
g --version/g -Vnow shows g's version (previously passed to VCS)Based on tmuxp#1010 and tmuxp#1011.
User-facing changes
CLI
g --versionandg -Vdisplay g's version instead of being passed to the underlying VCSDocumentation
/cli/with argparse-generated command referenceTechnical changes
docs/_ext/sphinx_argparse_neo/- argparse documentation with headerlinksdocs/_ext/argparse_lexer.py- syntax highlighting for CLI outputdocs/_ext/argparse_roles.py- semantic markup roles (:cli-opt:,:cli-cmd:, etc.)docs/_ext/argparse_exemplar.py- epilog examples transformationdocs/_static/css/argparse-highlight.css- CLI stylingtests/docs/_ext/docs/conf.pywith extension configurationpyproject.tomlwith mypy overridesTest plan
g --versionprintsg X.Y.Zg -Vprintsg X.Y.ZReferences